/**
 * ***************************************************************************** Copyright (c) 2000,
 * 2009 IBM Corporation and others. All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0 which accompanies this
 * distribution, and is available at http://www.eclipse.org/legal/epl-v10.html
 *
 * <p>Contributors: IBM Corporation - initial API and implementation
 * *****************************************************************************
 */
package org.eclipse.core.resources;

import org.eclipse.core.internal.watson.IElementComparator;
import org.eclipse.core.resources.mapping.IResourceChangeDescriptionFactory;
import org.eclipse.core.runtime.*;

/**
 * A resource delta represents changes in the state of a resource tree between two discrete points
 * in time.
 *
 * <p>Resource deltas implement the <code>IAdaptable</code> interface; extensions are managed by the
 * platform's adapter manager.
 *
 * @see IResource
 * @see Platform#getAdapterManager()
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface IResourceDelta extends IAdaptable {

  /*====================================================================
   * Constants defining resource delta kinds:
   *====================================================================*/

  /**
   * Delta kind constant indicating that the resource has not been changed in any way.
   *
   * @see IResourceDelta#getKind()
   */
  public static final int NO_CHANGE = IElementComparator.K_NO_CHANGE;

  /**
   * Delta kind constant (bit mask) indicating that the resource has been added to its parent. That
   * is, one that appears in the "after" state, not in the "before" one.
   *
   * @see IResourceDelta#getKind()
   */
  public static final int ADDED = 0x1;

  /**
   * Delta kind constant (bit mask) indicating that the resource has been removed from its parent.
   * That is, one that appears in the "before" state, not in the "after" one.
   *
   * @see IResourceDelta#getKind()
   */
  public static final int REMOVED = 0x2;

  /**
   * Delta kind constant (bit mask) indicating that the resource has been changed. That is, one that
   * appears in both the "before" and "after" states.
   *
   * @see IResourceDelta#getKind()
   */
  public static final int CHANGED = 0x4;

  /**
   * Delta kind constant (bit mask) indicating that a phantom resource has been added at the
   * location of the delta node.
   *
   * @see IResourceDelta#getKind()
   */
  public static final int ADDED_PHANTOM = 0x8;

  /**
   * Delta kind constant (bit mask) indicating that a phantom resource has been removed from the
   * location of the delta node.
   *
   * @see IResourceDelta#getKind()
   */
  public static final int REMOVED_PHANTOM = 0x10;

  /**
   * The bit mask which describes all possible delta kinds, including ones involving phantoms.
   *
   * @see IResourceDelta#getKind()
   */
  public static final int ALL_WITH_PHANTOMS =
      CHANGED | ADDED | REMOVED | ADDED_PHANTOM | REMOVED_PHANTOM;

  /*====================================================================
   * Constants which describe resource changes:
   *====================================================================*/

  /**
   * Change constant (bit mask) indicating that the content of the resource has changed.
   *
   * @see IResourceDelta#getFlags()
   */
  public static final int CONTENT = 0x100;

  /**
   * Change constant (bit mask) indicating that the resource was moved from another location. The
   * location in the "before" state can be retrieved using <code>getMovedFromPath()</code>.
   *
   * @see IResourceDelta#getFlags()
   */
  public static final int MOVED_FROM = 0x1000;

  /**
   * Change constant (bit mask) indicating that the resource was moved to another location. The
   * location in the new state can be retrieved using <code>getMovedToPath()</code>.
   *
   * @see IResourceDelta#getFlags()
   */
  public static final int MOVED_TO = 0x2000;

  /**
   * Change constant (bit mask) indicating that the resource was copied from another location. The
   * location in the "before" state can be retrieved using <code>getMovedFromPath()</code>. This
   * flag is only used when describing potential changes using an {@link
   * IResourceChangeDescriptionFactory}.
   *
   * @see IResourceDelta#getFlags()
   * @since 3.2
   */
  public static final int COPIED_FROM = 0x800;
  /**
   * Change constant (bit mask) indicating that the resource was opened or closed. This flag is also
   * set when the project did not exist in the "before" state. For example, if the current state of
   * the resource is open then it was previously closed or did not exist.
   *
   * @see IResourceDelta#getFlags()
   */
  public static final int OPEN = 0x4000;

  /**
   * Change constant (bit mask) indicating that the type of the resource has changed.
   *
   * @see IResourceDelta#getFlags()
   */
  public static final int TYPE = 0x8000;

  /**
   * Change constant (bit mask) indicating that the resource's sync status has changed. This type of
   * change is not included in build deltas, only in those for resource notification.
   *
   * @see IResourceDelta#getFlags()
   */
  public static final int SYNC = 0x10000;

  /**
   * Change constant (bit mask) indicating that the resource's markers have changed. This type of
   * change is not included in build deltas, only in those for resource notification.
   *
   * @see IResourceDelta#getFlags()
   */
  public static final int MARKERS = 0x20000;

  /**
   * Change constant (bit mask) indicating that the resource has been replaced by another at the
   * same location (i.e., the resource has been deleted and then added).
   *
   * @see IResourceDelta#getFlags()
   */
  public static final int REPLACED = 0x40000;

  /**
   * Change constant (bit mask) indicating that a project's description has changed.
   *
   * @see IResourceDelta#getFlags()
   */
  public static final int DESCRIPTION = 0x80000;

  /**
   * Change constant (bit mask) indicating that the encoding of the resource has changed.
   *
   * @see IResourceDelta#getFlags()
   * @since 3.0
   */
  public static final int ENCODING = 0x100000;

  /**
   * Change constant (bit mask) indicating that the underlying file or folder of the linked resource
   * has been added or removed.
   *
   * @see IResourceDelta#getFlags()
   * @since 3.4
   */
  public static final int LOCAL_CHANGED = 0x200000;

  /**
   * Change constant (bit mask) indicating that the derived flag of the resource has changed.
   *
   * @see IResourceDelta#getFlags()
   * @since 3.6
   */
  public static final int DERIVED_CHANGED = 0x400000;

  /**
   * Accepts the given visitor. The only kinds of resource deltas visited are <code>ADDED</code>,
   * <code>REMOVED</code>, and <code>CHANGED</code>. The visitor's <code>visit</code> method is
   * called with this resource delta if applicable. If the visitor returns <code>true</code>, the
   * resource delta's children are also visited.
   *
   * <p>This is a convenience method, fully equivalent to <code>accept(visitor, IResource.NONE)
   * </code>. Although the visitor will be invoked for this resource delta, it will not be invoked
   * for any team-private member resources.
   *
   * @param visitor the visitor
   * @exception CoreException if the visitor failed with this exception.
   * @see IResourceDeltaVisitor#visit(IResourceDelta)
   */
  public void accept(IResourceDeltaVisitor visitor) throws CoreException;

  /**
   * Accepts the given visitor. The visitor's <code>visit</code> method is called with this resource
   * delta. If the visitor returns <code>true</code>, the resource delta's children are also
   * visited.
   *
   * <p>This is a convenience method, fully equivalent to:
   *
   * <pre>
   *   accept(visitor, includePhantoms ? INCLUDE_PHANTOMS : IResource.NONE);
   * </pre>
   *
   * Although the visitor will be invoked for this resource delta, it will not be invoked for any
   * team-private member resources.
   *
   * @param visitor the visitor
   * @param includePhantoms <code>true</code> if phantom resources are of interest; <code>false
   *     </code> if phantom resources are not of interest
   * @exception CoreException if the visitor failed with this exception.
   * @see #accept(IResourceDeltaVisitor)
   * @see IResource#isPhantom()
   * @see IResourceDeltaVisitor#visit(IResourceDelta)
   */
  public void accept(IResourceDeltaVisitor visitor, boolean includePhantoms) throws CoreException;

  /**
   * Accepts the given visitor. The visitor's <code>visit</code> method is called with this resource
   * delta. If the visitor returns <code>true</code>, the resource delta's children are also
   * visited.
   *
   * <p>The member flags determine which child deltas of this resource delta will be visited. The
   * visitor will always be invoked for this resource delta.
   *
   * <p>If the <code>INCLUDE_PHANTOMS</code> member flag is not specified (recommended), only child
   * resource deltas involving existing resources will be visited (kinds <code>ADDED</code>, <code>
   * REMOVED</code>, and <code>CHANGED</code>). If the <code>INCLUDE_PHANTOMS</code> member flag is
   * specified, the result will also include additions and removes of phantom resources (kinds
   * <code>ADDED_PHANTOM</code> and <code>REMOVED_PHANTOM</code>).
   *
   * <p>If the <code>INCLUDE_TEAM_PRIVATE_MEMBERS</code> member flag is not specified (recommended),
   * resource deltas involving team private member resources will be excluded from the visit. If the
   * <code>INCLUDE_TEAM_PRIVATE_MEMBERS</code> member flag is specified, the visit will also include
   * additions and removes of team private member resources.
   *
   * @param visitor the visitor
   * @param memberFlags bit-wise or of member flag constants (<code>IContainer.INCLUDE_PHANTOMS
   *     </code>, <code>INCLUDE_HIDDEN</code> and <code>INCLUDE_TEAM_PRIVATE_MEMBERS</code>)
   *     indicating which members are of interest
   * @exception CoreException if the visitor failed with this exception.
   * @see IResource#isPhantom()
   * @see IResource#isTeamPrivateMember()
   * @see IResource#isHidden()
   * @see IContainer#INCLUDE_PHANTOMS
   * @see IContainer#INCLUDE_TEAM_PRIVATE_MEMBERS
   * @see IContainer#INCLUDE_HIDDEN
   * @see IResourceDeltaVisitor#visit(IResourceDelta)
   * @since 2.0
   */
  public void accept(IResourceDeltaVisitor visitor, int memberFlags) throws CoreException;

  /**
   * Finds and returns the descendent delta identified by the given path in this delta, or <code>
   * null</code> if no such descendent exists. The supplied path may be absolute or relative; in
   * either case, it is interpreted as relative to this delta. Trailing separators are ignored. If
   * the path is empty this delta is returned.
   *
   * <p>This is a convenience method to avoid manual traversal of the delta tree in cases where the
   * listener is only interested in changes to particular resources. Calling this method will
   * generally be faster than manually traversing the delta to a particular descendent.
   *
   * @param path the path of the desired descendent delta
   * @return the descendent delta, or <code>null</code> if no such descendent exists in the delta
   * @since 2.0
   */
  public IResourceDelta findMember(IPath path);

  /**
   * Returns resource deltas for all children of this resource which were added, removed, or
   * changed. Returns an empty array if there are no affected children.
   *
   * <p>This is a convenience method, fully equivalent to:
   *
   * <pre>
   *   getAffectedChildren(ADDED | REMOVED | CHANGED, IResource.NONE);
   * </pre>
   *
   * Team-private member resources are <b>not</b> included in the result; neither are phantom
   * resources.
   *
   * @return the resource deltas for all affected children
   * @see IResourceDelta#ADDED
   * @see IResourceDelta#REMOVED
   * @see IResourceDelta#CHANGED
   * @see #getAffectedChildren(int,int)
   */
  public IResourceDelta[] getAffectedChildren();

  /**
   * Returns resource deltas for all children of this resource whose kind is included in the given
   * mask. Kind masks are formed by the bitwise or of <code>IResourceDelta</code> kind constants.
   * Returns an empty array if there are no affected children.
   *
   * <p>This is a convenience method, fully equivalent to:
   *
   * <pre>
   *   getAffectedChildren(kindMask, IResource.NONE);
   * </pre>
   *
   * Team-private member resources are <b>not</b> included in the result.
   *
   * @param kindMask a mask formed by the bitwise or of <code>IResourceDelta </code> delta kind
   *     constants
   * @return the resource deltas for all affected children
   * @see IResourceDelta#ADDED
   * @see IResourceDelta#REMOVED
   * @see IResourceDelta#CHANGED
   * @see IResourceDelta#ADDED_PHANTOM
   * @see IResourceDelta#REMOVED_PHANTOM
   * @see IResourceDelta#ALL_WITH_PHANTOMS
   * @see #getAffectedChildren(int,int)
   */
  public IResourceDelta[] getAffectedChildren(int kindMask);

  /**
   * Returns resource deltas for all children of this resource whose kind is included in the given
   * mask. Masks are formed by the bitwise or of <code>IResourceDelta</code> kind constants. Returns
   * an empty array if there are no affected children.
   *
   * <p>If the <code>INCLUDE_TEAM_PRIVATE_MEMBERS</code> member flag is not specified,
   * (recommended), resource deltas involving team private member resources will be excluded. If the
   * <code>INCLUDE_TEAM_PRIVATE_MEMBERS</code> member flag is specified, the result will also
   * include resource deltas of the specified kinds to team private member resources.
   *
   * <p>If the {@link IContainer#INCLUDE_HIDDEN} member flag is not specified, (recommended),
   * resource deltas involving hidden resources will be excluded. If the {@link
   * IContainer#INCLUDE_HIDDEN} member flag is specified, the result will also include resource
   * deltas of the specified kinds to hidden resources.
   *
   * <p>Specifying the <code>IContainer.INCLUDE_PHANTOMS</code> member flag is equivalent to
   * including <code>IContainer.ADDED_PHANTOM</code> and <code>IContainer.REMOVED_PHANTOM</code> in
   * the kind mask.
   *
   * @param kindMask a mask formed by the bitwise or of <code>IResourceDelta</code> delta kind
   *     constants
   * @param memberFlags bit-wise or of member flag constants (<code>IContainer.INCLUDE_PHANTOMS
   *     </code>, <code>IContainer.INCLUDE_TEAM_PRIVATE_MEMBERS</code> and <code>
   *     IContainer.INCLUDE_HIDDEN</code>) indicating which members are of interest
   * @return the resource deltas for all affected children
   * @see IResourceDelta#ADDED
   * @see IResourceDelta#REMOVED
   * @see IResourceDelta#CHANGED
   * @see IResourceDelta#ADDED_PHANTOM
   * @see IResourceDelta#REMOVED_PHANTOM
   * @see IResourceDelta#ALL_WITH_PHANTOMS
   * @see IContainer#INCLUDE_PHANTOMS
   * @see IContainer#INCLUDE_TEAM_PRIVATE_MEMBERS
   * @see IContainer#INCLUDE_HIDDEN
   * @since 2.0
   */
  public IResourceDelta[] getAffectedChildren(int kindMask, int memberFlags);

  /**
   * Returns flags which describe in more detail how a resource has been affected.
   *
   * <p>The following codes (bit masks) are used when kind is <code>CHANGED</code>, and also when
   * the resource is involved in a move:
   *
   * <ul>
   *   <li><code>CONTENT</code> - The bytes contained by the resource have been altered, or <code>
   *       IResource.touch</code> has been called on the resource.
   *   <li><code>DERIVED_CHANGED</code> - The derived flag of the resource has been altered.
   *   <li><code>ENCODING</code> - The encoding of the resource may have been altered. This flag is
   *       not set when the encoding changes due to the file being modified, or being moved.
   *   <li><code>DESCRIPTION</code> - The description of the project has been altered, or <code>
   *       IResource.touch</code> has been called on the project. This flag is only valid for
   *       project resources.
   *   <li><code>OPEN</code> - The project's open/closed state has changed. If it is not open, it
   *       was closed, and vice versa. This flag is only valid for project resources.
   *   <li><code>TYPE</code> - The resource (a folder or file) has changed its type.
   *   <li><code>SYNC</code> - The resource's sync status has changed.
   *   <li><code>MARKERS</code> - The resource's markers have changed.
   *   <li><code>REPLACED</code> - The resource (and all its properties) was deleted (either by a
   *       delete or move), and was subsequently re-created (either by a create, move, or copy).
   *   <li><code>LOCAL_CHANGED</code> - The resource is a linked resource, and the underlying file
   *       system object has been added or removed.
   * </ul>
   *
   * The following code is only used if kind is <code>REMOVED</code> (or <code>CHANGED</code> in
   * conjunction with <code>REPLACED</code>):
   *
   * <ul>
   *   <li><code>MOVED_TO</code> - The resource has moved. <code>getMovedToPath</code> will return
   *       the path of where it was moved to.
   * </ul>
   *
   * The following code is only used if kind is <code>ADDED</code> (or <code>CHANGED</code> in
   * conjunction with <code>REPLACED</code>):
   *
   * <ul>
   *   <li><code>MOVED_FROM</code> - The resource has moved. <code>getMovedFromPath</code> will
   *       return the path of where it was moved from.
   * </ul>
   *
   * The following code is only used when describing potential changes using an {@link
   * IResourceChangeDescriptionFactory}:
   *
   * <ul>
   *   <li><code>COPIED_FROM</code> - Change constant (bit mask) indicating that the resource was
   *       copied from another location. The location in the "before" state can be retrieved using
   *       <code>getMovedFromPath()</code>.
   * </ul>
   *
   * A simple move operation would result in the following delta information. If a resource is moved
   * from A to B (with no other changes to A or B), then A will have kind <code>REMOVED</code>, with
   * flag <code>MOVED_TO</code>, and <code>getMovedToPath</code> on A will return the path for B. B
   * will have kind <code>ADDED</code>, with flag <code>MOVED_FROM</code>, and <code>
   * getMovedFromPath</code> on B will return the path for A. B's other flags will describe any
   * other changes to the resource, as compared to its previous location at A.
   *
   * <p>Note that the move flags only describe the changes to a single resource; they don't
   * necessarily imply anything about the parent or children of the resource. If the children were
   * moved as a consequence of a subtree move operation, they will have corresponding move flags as
   * well.
   *
   * <p>Note that it is possible for a file resource to be replaced in the workspace by a folder
   * resource (or the other way around). The resource delta, which is actually expressed in terms of
   * paths instead or resources, shows this as a change to either the content or children.
   *
   * @return the flags
   * @see IResourceDelta#CONTENT
   * @see IResourceDelta#DERIVED_CHANGED
   * @see IResourceDelta#DESCRIPTION
   * @see IResourceDelta#ENCODING
   * @see IResourceDelta#LOCAL_CHANGED
   * @see IResourceDelta#OPEN
   * @see IResourceDelta#MOVED_TO
   * @see IResourceDelta#MOVED_FROM
   * @see IResourceDelta#COPIED_FROM
   * @see IResourceDelta#TYPE
   * @see IResourceDelta#SYNC
   * @see IResourceDelta#MARKERS
   * @see IResourceDelta#REPLACED
   * @see #getKind()
   * @see #getMovedFromPath()
   * @see #getMovedToPath()
   * @see IResource#move(IPath, int, IProgressMonitor)
   */
  public int getFlags();

  /**
   * Returns the full, absolute path of this resource delta.
   *
   * <p>Note: the returned path never has a trailing separator.
   *
   * @return the full, absolute path of this resource delta
   * @see IResource#getFullPath()
   * @see #getProjectRelativePath()
   */
  public IPath getFullPath();

  /**
   * Returns the kind of this resource delta. Normally, one of <code>ADDED</code>, <code>REMOVED
   * </code>, <code>CHANGED</code>. When phantom resources have been explicitly requested, there are
   * two additional kinds: <code>ADDED_PHANTOM</code> and <code>REMOVED_PHANTOM</code>.
   *
   * @return the kind of this resource delta
   * @see IResourceDelta#ADDED
   * @see IResourceDelta#REMOVED
   * @see IResourceDelta#CHANGED
   * @see IResourceDelta#ADDED_PHANTOM
   * @see IResourceDelta#REMOVED_PHANTOM
   */
  public int getKind();

  /**
   * Returns the changes to markers on the corresponding resource. Returns an empty array if no
   * markers changed.
   *
   * @return the marker deltas
   */
  public IMarkerDelta[] getMarkerDeltas();

  /**
   * Returns the full path (in the "before" state) from which this resource (in the "after" state)
   * was moved. This value is only valid if the <code>MOVED_FROM</code> change flag is set;
   * otherwise, <code>null</code> is returned.
   *
   * <p>Note: the returned path never has a trailing separator.
   *
   * @return a path, or <code>null</code>
   * @see #getMovedToPath()
   * @see #getFullPath()
   * @see #getFlags()
   */
  public IPath getMovedFromPath();

  /**
   * Returns the full path (in the "after" state) to which this resource (in the "before" state) was
   * moved. This value is only valid if the <code>MOVED_TO</code> change flag is set; otherwise,
   * <code>null</code> is returned.
   *
   * <p>Note: the returned path never has a trailing separator.
   *
   * @return a path, or <code>null</code>
   * @see #getMovedFromPath()
   * @see #getFullPath()
   * @see #getFlags()
   */
  public IPath getMovedToPath();

  /**
   * Returns the project-relative path of this resource delta. Returns the empty path for projects
   * and the workspace root.
   *
   * <p>A resource's project-relative path indicates the route from the project to the resource.
   * Within a workspace, there is exactly one such path for any given resource. The returned path
   * never has a trailing separator.
   *
   * @return the project-relative path of this resource delta
   * @see IResource#getProjectRelativePath()
   * @see #getFullPath()
   * @see Path#EMPTY
   */
  public IPath getProjectRelativePath();

  /**
   * Returns a handle for the affected resource.
   *
   * <p>For additions (<code>ADDED</code>), this handle describes the newly-added resource; i.e.,
   * the one in the "after" state.
   *
   * <p>For changes (<code>CHANGED</code>), this handle also describes the resource in the "after"
   * state. When a file or folder resource has changed type, the former type of the handle can be
   * inferred.
   *
   * <p>For removals (<code>REMOVED</code>), this handle describes the resource in the "before"
   * state. Even though this resource would not normally exist in the current workspace, the type of
   * resource that was removed can be determined from the handle.
   *
   * <p>For phantom additions and removals (<code>ADDED_PHANTOM</code> and <code>REMOVED_PHANTOM
   * </code>), this is the handle of the phantom resource.
   *
   * @return the affected resource (handle)
   */
  public IResource getResource();
}
